package net.wanderinghorse.json;

import java.lang.String;

/**
 * An interface for JSON-centric classes which want to tightly control
 * their JSON input/output structure.
 *
 * The AbstractJSONable class implements all but two of the methods,
 * so it is often easier to subclass that type than to implement
 * all of the methods oneself. That said, the other functions can
 * all be implemented as one-line wrappers around the two "real"
 * functions (toJSONObject() and fromJSONObject()).
 */
public interface JSONable
{
    /**
     * Must return a JSON-compliant representation of this object,
     * in the form of a JSONObject.
     *
     * @return The JSONObject representation.
     * @throws JSONException if any of the underlying JSONObject members throws.
     *  Implementations may throw other unchecked exceptions.
     */
    public JSONObject toJSONObject();

    /**
     * Equivalent to this.toJSONObject().toString().
     *
     * @return This object's JSON form.
     * @throws JSONException If the underlying JSONObject API throws.
     */
    public String toJSON();

    /**
     * Equivalent to this.toJSONObject().toString(indention).
     *
     * @param indention See JSONObject.toString(int).
     * @return This object's JSON form.
     * @throws JSONException If the underlying JSONObject API throws.
     */
    public String toJSON(int indention);

    /**
     * Must populate this object from the given JSON source.
     *
     * @param src The source JSON data.
     * @throws JSONException If any JSONObject members throw. Implementations
     * may optionally throw if the input object violates the expected structure.
     */
    public void fromJSONObject( final JSONObject src );

    /**
     * Equivalent to this.fromJSONObject( new JSONObject(src) ).
     *
     * @param src JSON string representation of this object.
     * @throws JSONException If any of the underlying JSONObject API throws.
     */
    public void fromJSON( final String src );
}